Setting Up the Files

The easiest file to set up is the address list. It consists of blocks of text separated by blank lines. Commonly, the first line of a block will be the name of an addressee, while the rest of the lines form the address. The address program therefore assigns these segments of text to the macros \Name and \Address, respectively.

Unlike normal TEX input, individual lines of text within an address (which can be of arbitrary length) retain their identity. This is accomplished by concatenating the lines, using \\ as a separator. For L^ATEX, this is quite convenient since a reference to \Address will result in the expansion of each \\ as a new line. In TEX, a similar effect can be obtained by

\def\\{\hfil\break}

In the template file, individual lines within \Address can be selected by \AddrLine{n}, where n is a positive integer. In addition, \Laddr will count the number of lines in \Address and \Naddr will refer to the current position in the address list.

It is often desirable to include other information along with the address. The easiest way to do this with address is to divide the lines of text in the address segment into subblocks, each of which can be of variable length. The macro call, \AddrBlock{k}, is provided to select the k^th subblock, where a line consisting of --- acts as a separator between subblocks. (Two consecutive lines of --- will not produce an empty subblock, but this effect can be achieved by inserting a line consisting of {} between the lines.)

To extract individual lines from a subblock of \Address, a two-step process is required. \StoreAddrBlock{k}\in\Block will define the contents of the macro \Block to be the k^th subblock of \Address. \GetLine{n}\of\Block will then select the n^th line of the \Block. This procedure is necessary to circumvent some peculiarities of TEX macro expansion.

One of the more salient features of address is the ability to intelligently parse the \Name and break it up into its components. For example, suppose the name is The Honorable and Mrs. Henry \& Matilda Edward Bo van Frothingham III, Royals. The following macro assignments will then be made when this name is parsed:

`\SocialTitle`	$ &rarr#rightarrow; $	The Honorable and Mrs.
`\FirstName`	$ &rarr#rightarrow; $	Henry `\`& Matilda
`\MiddleName`	$ &rarr#rightarrow; $	Edward Bo
`\LastName`	$ &rarr#rightarrow; $	van Frothingham
`\Suffix`	$ &rarr#rightarrow; $	III
`\OtherTitle`	$ &rarr#rightarrow; $	Royals

Simpler names will result in some of the above macros having null definitions.

The macros associated with the address program are summarized in the following table.


`\DEFAULTtolist`	default address list (initially, `tolist`)
`\DEFAULTletter`	default letter template (initially, `letter`)

`\Name`	first line of the address
`\Address`	subsequent lines of the address
`\SocialTitle`	e.g., Dr., Mr., Ms.
`\FirstName`	first name
`\MiddleName`	middle names
`\LastName`	last name
`\Suffix`	e.g., Sr., Jr., III
`\OtherTitle`	academic and professional titles

`\Naddr`	position of the address in the `tolist`
`\Laddr`	number of lines in `\Address`
`\AddrLine{`n`}`	n^th line of `\Address`
`\AddrBlock{`n`}`	n^th subblock of `\Address`
`\StoreAddrBlock{`n`}\in\B`	store the n^th subblock of `\Address` in `\B`
`\GetLine{`n`}\of\B`	n^th line of `\B`

`\addspace\A`	adds a space after `\A` if it is not null
`\topbox{`H`}{`W`}{text}`	top aligned box of height H and width W

An example of an address list appears below. Notice that following the address in each instance is a separate block of two lines.

Mrs. Apple Thesaurus
Apt. Z
234 Gestalt Lane
Cockermouth, Umbria, U.K.
---
artichokes
jalape\~nos

Harry K. Banana
P.O. Box 29Z46
Kahului, Maui, Hawaii
---
mustard greens
okra

A typical (L^ATEX) letter template that might be used with the above list of addresses looks like:

\Name\\
\AddrBlock{1}

\StoreAddrBlock{2}\in\veggies
Dear \addspace\SocialTitle\LastName:

Welcome to the vegetable of the month
club!  Your introductory offer of
two selections this first month are
\GetLine{1}\of\veggies\ and
\GetLine{2}\of\veggies.  ...
\newpage

The macro \addspace is used to produce correct spacing in the salutation by adding a proper space after \SocialTitle if it contains text and doing nothing if \SocialTitle is empty (as would be the case for the second addressee).

The last file needed by address is the preamble. This file is \input once and is used to perform initializations, such as setting margins and defining macros. If address is being L^ATEXed, the preamble is input before the \begin{document} that is executed automatically before processing the addresses. A sample preamble that can be used under TEX or L^ATEX is given below. (The definition for \ifundefined can be found in Knuth [page 40] and is present in address.)

%
% Generic TeX/LaTeX preamble for
%    address.tex .
%
\ifundefined{LaTeX}             % TeX
   \magnification=\magstep1
   \voffset=0in
   \hoffset=0in
   \vsize=9in
   \hsize=6.5in
   \nopagenumbers
   %
   \def\\{\hfil\break}
   \def\newpage{\vfil\eject}
\else                           % LaTeX
   \documentstyle[12pt]{letter}
   \topmargin 0in
   \headheight 0in
   \headsep 0in
   \oddsidemargin 0in
   \textheight 9in
   \textwidth 6.5in
   \pagestyle{empty}
\fi